home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 May: Tool Chest / Developer CD Series May 1996 (Tool Chest) (Apple Computer) (1996).iso / Sample Code / Snippets / Devices / SCSI Simple Sample / Src / LogManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-03-24  |  9.2 KB  |  330 lines  |  [TEXT/KAHL]
  1. /*                                    LogManager.h                                */
  2. /*
  3.  * LogManager.h
  4.  * Copyright © 1993 Apple Computer Inc. All rights reserved.
  5.  *
  6.  * These functions manage a logging display for error messages and other text.
  7.  * The log is implemented as a ListManager list that can hold nLogItems. This
  8.  * module is intentionally more-or-less self-contained so it can easily be
  9.  * exported to other applications.
  10.  */
  11. #ifndef __LogManager__
  12. #define __LogManager__
  13. #ifndef THINK_C                /* MPW includes            */
  14. #include <Errors.h>
  15. #include <Script.h>
  16. #include <Types.h>
  17. #include <Resources.h>
  18. #include <QuickDraw.h>
  19. #include <Fonts.h>
  20. #include <Events.h>
  21. #include <Windows.h>
  22. #include <ToolUtils.h>
  23. #include <Memory.h>
  24. #include <Lists.h>
  25. #endif
  26. #include <Printing.h>
  27.  
  28. /*
  29.  * Usage:
  30.  *        ListHandle                    CreateLog(
  31.  *                const Rect                *viewRect,
  32.  *                short                    listFontNumber,
  33.  *                short                    listFontSize,
  34.  *                short                    nLogLines
  35.  *            );
  36.  *    Create a new log display in the current window. To define a log, first
  37.  *    SetPort to the window, and pass viewRect in window coordinates. Returns
  38.  *    NULL on errors. if nLogLines is zero, a default value (128) will be used.
  39.  *    Note: the log will be displayed with a horizontal and vertical scrollbar.
  40.  *    Be sure to dimension the viewRect to leave room for both: they are not
  41.  *    included in the viewRect (for compatibility with other ListManager calls).
  42.  *
  43.  *        void                        DisposeLog(
  44.  *                ListHandle                logListHandle
  45.  *            );
  46.  *    Dispose of the log. logListHandle may be NULL without disasterous results.
  47.  *
  48.  *        Boolean                        DoClickInLog(
  49.  *                ListHandle                logListHandle,
  50.  *                const EventRecord        *eventRecord
  51.  *            );
  52.  *    Called on a mouse-down in the log viewRect. Returns FALSE if the mouse-down
  53.  *    wasn't in the viewRect (this isn't really an error, but lets you call
  54.  *    DoClickInLog on all mouseDown's). Note: the port should be set to the log
  55.  *    window. You cannot select text in the log. This is a limitation:
  56.  *    Copy to the Clipboard would be useful.
  57.  *
  58.  *        void                        UpdateLog(
  59.  *                ListHandle                logListHandle
  60.  *            );
  61.  *    Called on update events in the log window. UpdateLog passes the window
  62.  *    visRgn to the List Manager.
  63.  *
  64.  *        void                        UpdateLogWindow(
  65.  *                ListHandle                logListHandle
  66.  *            );
  67.  *    Called to update the log area without an update event. This may be used
  68.  *    after displaying a dialog or alert that might have obscured the window.
  69.  *
  70.  *        void                        ActivateLog(
  71.  *                ListHandle                logListHandle,
  72.  *                Boolean                    activating
  73.  *            );
  74.  *    Called on activate, deactivate, suspend and resume events.
  75.  *
  76.  *        void                        MoveLog(
  77.  *                ListHandle                logListHandle,
  78.  *                short                    leftEdge,
  79.  *                short                    topEdge
  80.  *            );
  81.  *    Called to move the log within the window (after resizing the window)
  82.  *    LeftEdge and topEdge are in window coordinates.
  83.  *
  84.  *        void                        SizeLog(
  85.  *                ListHandle                logListHandle,
  86.  *                short                    newWidth,
  87.  *                short                    newHeight
  88.  *            );
  89.  *    Resize the log area (after resizing the window). NewWidth and NewHeight
  90.  *    are in window coordinates.
  91.  *
  92.  * The following calls display data in the log.
  93.  *
  94.  *        void                        LogStatus(
  95.  *                ListHandle                logListHandle,
  96.  *                OSErr                    theError,
  97.  *                ConstStr255Param        infoText
  98.  *            );
  99.  *    If theError is not noErr, display the error value and infoText in the log.
  100.  *
  101.  *        void                        DisplayLogString(
  102.  *                ListHandle                logListHandle,
  103.  *                ConstStr255Param        theString
  104.  *            );
  105.  *    Display the argument string in the log.
  106.  *
  107.  *
  108.  * File I/O
  109.  *
  110.  *        OSErr                        SaveLogFile(
  111.  *                ListHandle                logListHandle,
  112.  *                ConstStr255Param        dialogPromptString,
  113.  *                ConstStr255Param        defaultFileName,
  114.  *                OSType                    creatorType
  115.  *            );
  116.  *    Prompt the user for a file name and write the current log contents
  117.  *    to the chosen file. Returns an error status (noErr is ok). This function
  118.  *    returns userCanceledErr if the user cancelled the SFPutFile dialog.
  119.  *
  120.  *        OSErr                        CreateLogFile(
  121.  *                ListHandle                logListHandle,
  122.  *                OSType                    creatorType,
  123.  *                ConstStr255Param        fileName,
  124.  *                short                    vRefNum
  125.  *            );
  126.  *    Create a log on the specified file and volume. Normally, called only
  127.  *    by SaveLogFile.
  128.  *
  129.  *        void                        WriteCurrentLog(
  130.  *                ListHandle                logListHandle
  131.  *            );
  132.  *    Write the current log to the file. This is called when the log file
  133.  *    is first created.
  134.  *
  135.  *        void                        WriteLogLine(
  136.  *                ListHandle                logListHandle,
  137.  *                ConstStr255Param        theText
  138.  *            );
  139.  *    Write a single line of text to the currently-open log, if any.
  140.  *    Any errors are stored in the INFO structure. WriteLogLine is
  141.  *    called to "dribble" new text into the log file.
  142.  *
  143.  *        OSErr                        CloseLogFile(
  144.  *                ListHandle                logListHandle
  145.  *            );
  146.  *    Close the currently active log file (if any). Returns the earliest
  147.  *    status (i.e., if the disk filled during a "dribble" operation, it
  148.  *    will return a device full error).
  149.  *
  150.  *        OSErr                        GetLogFileError(
  151.  *                ListHandle                logListHandle
  152.  *            );
  153.  *    Return the last file error stored in the log record.
  154.  *
  155.  *        Boolean                        HasLogFile(
  156.  *                ListHandle                logListHandle
  157.  *            );
  158.  *    TRUE if a log file is currently open.
  159.  *
  160.  * This function prints the log
  161.  *
  162.  *        OSErr                        PrintLog(
  163.  *                ListHandle                logListHandle,
  164.  *                THPrint                    hPrint
  165.  *            );
  166.  *    Print the current contents of the log. if hPrint is non-null, it will
  167.  *    be used to configure the printer. Otherwise, a Print Handle will be
  168.  *    allocated (and disposed) internally. No page numbers or headers or
  169.  *    other useful stuff. Sorry.
  170.  */
  171.  
  172. /*
  173.  * This record is stored in the userHandle variable in the list. The values are
  174.  * needed to specify the font, limit the number of error log lines that are stored,
  175.  * and preserve the log area color. We also hide the horizontal scrollbar here
  176.  * because, if we leave it in the ListRecord, the ListManager will decide to
  177.  * permanently un-hilite it.
  178.  *
  179.  * Note: the LogInfoRecord is private to the LogManager routines.
  180.  */
  181. typedef struct LogInfoRecord {
  182.         ControlHandle        hScroll;
  183.         short                logLines;
  184.         short                fontNumber;
  185.         short                fontSize;
  186.         RGBColor            foreColor;
  187.         RGBColor            backColor;
  188.         short                logFileRefNum;        /* Non-zero if log file open    */
  189.         short                logFileVRefNum;        /* Log file volume refNum        */
  190.         OSErr                logFileStatus;        /* noError or last log file err    */
  191. } LogInfoRecord, *LogInfoPtr, **LogInfoHdl;
  192.  
  193. /*
  194.  * CreateLog
  195.  *        Create a new log display in the current window. To define a log, first
  196.  *        SetPort to the window, and pass viewRect in window coordinates. Returns
  197.  *        NULL on errors. if nLogLines is zero, a default value (128) will be used.
  198.  *        Note: the log will be displayed with a horizontal and vertical scrollbar.
  199.  *        Be sure to dimension the viewRect to leave room for both.
  200.  */
  201. ListHandle                            CreateLog(
  202.         const Rect                        *viewRect,
  203.         short                            listFontNumber,
  204.         short                            listFontSize,
  205.         short                            nLogLines
  206.     );
  207. /*
  208.  * DisposeLog
  209.  *        Dispose of the log. logListHandle may be NULL.
  210.  */
  211. void                                DisposeLog(
  212.         ListHandle                        logListHandle
  213.     );
  214. /*
  215.  * DoClickInLog
  216.  *        Call on a mouse-down in the log viewRect. Returns FALSE if the mouse-down
  217.  *        wasn't in the viewRect (this isn't really an error, but lets you call
  218.  *        DoClickInLog on all mouseDown's). Note: the port should be set to the log
  219.  *        window. You cannot select text in the log.
  220.  */
  221. Boolean                                DoClickInLog(
  222.         ListHandle                        logListHandle,
  223.         const EventRecord                *eventRecord
  224.     );
  225. /*
  226.  * UpdateLog
  227.  *        Call on update events in the log window.
  228.  */
  229. void                                UpdateLog(
  230.         ListHandle                        logListHandle
  231.     );
  232. /*
  233.  * UpdateLogWindow
  234.  *        Call to force an update on the log's window. This may be used after
  235.  *        displaying a dialog or alert that might have obscured the window.
  236.  */
  237. void                                UpdateLogWindow(
  238.         ListHandle                        logListHandle
  239.     );
  240. /*
  241.  * ActivateLog
  242.  *        Call on activate, suspend, and resume events.
  243.  */
  244. void                                ActivateLog(
  245.         ListHandle                        logListHandle,
  246.         Boolean                            activating
  247.     );
  248. /*
  249.  * MoveLog
  250.  *        Move the log area within the window.
  251.  */
  252. void                                MoveLog(
  253.         ListHandle                        logListHandle,
  254.         short                            leftEdge,
  255.         short                            topEdge
  256.     );
  257. /*
  258.  * SizeLog
  259.  *        Change the size of the log area.
  260.  */
  261. void                                SizeLog(
  262.         ListHandle                        logListHandle,
  263.         short                            newWidth,
  264.         short                            newHeight
  265.     );
  266. /*
  267.  * LogStatus
  268.  *        Call with an error status code and some text to display.
  269.  */
  270. void                                LogStatus(
  271.         ListHandle                        logListHandle,
  272.         OSErr                            theError,
  273.         const StringPtr                    infoText
  274.     );
  275. /*
  276.  * DisplayLogString
  277.  *        Call with some text to display.
  278.  */
  279. void                                DisplayLogString(
  280.         ListHandle                        logListHandle,
  281.         const StringPtr                    theString
  282.     );
  283. StringHandle                        GetLogStringHandle(
  284.         ListHandle                        logListHandle,
  285.         short                            theRow
  286.     );
  287. /*
  288.  * Log file functions.
  289.  */
  290. OSErr                                SaveLogFile(
  291.         ListHandle                        logListHandle,
  292.          ConstStr255Param                dialogPromptString,
  293.         ConstStr255Param                defaultFileName,
  294.         OSType                            creatorType
  295.     );
  296.  
  297. OSErr                                CreateLogFile(
  298.         ListHandle                        logListHandle,
  299.         OSType                            creatorType,
  300.         ConstStr255Param                fileName,
  301.         short                            vRefNum
  302.     );
  303. void                                WriteCurrentLog(
  304.         ListHandle                        logListHandle
  305.     );
  306. void                                WriteLogLine(
  307.         ListHandle                        logListHandle,
  308.         ConstStr255Param                theText
  309.     );
  310. OSErr                                CloseLogFile(
  311.         ListHandle                        logListHandle
  312.     );
  313. OSErr                                GetLogFileError(
  314.         ListHandle                        logListHandle
  315.     );
  316. Boolean                                HasLogFile(
  317.         ListHandle                        logListHandle
  318.     );
  319. /*
  320.  * Print the log.
  321.  */
  322. OSErr                                PrintLog(
  323.         ListHandle                        logListHandle,
  324.         THPrint                            hPrint
  325.     );
  326. #endif /* __LogManager__ */
  327.  
  328.  
  329.  
  330.